Release 10.1A: OpenEdge Development:
Web Services

WSDL and the Web service interface

Most Web service providers publicize and describe the public interface to their Web services using WSDL. OpenEdge requires that you have access to a valid WSDL file that describes the Web service you need to access. The WSDL file that you obtain from the Web service provider provides accurate information on the Web service interface, including the interface definition of Web service operations and the precise binding requirements to physically access the Web service on the network from your 4GL application. For more information on WSDL and Web services architecture, see the sections on OpenEdge support for Web services in OpenEdge Getting Started: Application and Integration Services . The following sections provide an overview of WSDL and how OpenEdge makes use of WSDL to make accessing Web services easier from the 4GL.

Note: Web services do not generally require that you have a WSDL file to access them. However, the Progress 4GL does require this file for both development and run-time access to the Web service.

WSDL—an overview

If you have built Web services in the 4GL, you might already be familiar with the basic structure of a WSDL file and how OpenEdge uses it to define 4GL Web services (see Chapter 2 "WSDL and Web Service Objects in Progress 4GL Web Services"). This section describes a WSDL file more generically, as it might define any Web service you might want to access from the 4GL.

Note: Accessing some Web services requires little, if any, knowledge of WSDL. However, for complex Web services, you must have a basic understanding of WSDL to make full use of the Web service and to access its data appropriately.

A single WSDL file describes a single Web service and contains a series of major sections that define features of the Web service interface, from data and operations to the binding information needed to access the Web service on the network. Each section is defined by a corresponding WSDL element.

Table 1–1 lists and describes these major WSDL sections in the order that they appear in a WSDL file.

Note: This information is similar to the description of WSDL file sections provided for Progress 4GL Web services (see Chapter 2 "WSDL and Web Service Objects in Progress 4GL Web Services"). However, Table 1–1 describes the WSDL sections from a more general perspective. The WSDL files that you see in the industry do not necessarily define Web services in the same way that OpenEdge uses them to define 4GL Web services.

Table 1–1: WSDL sections overview

Section	Description
Definitions	Defined by one occurrence of the <definitions> element. This section identifies the Web service, defines all valid namespaces for the WSDL file, and encapsulates all other WSDL sections. Each Web service has a unique namespace (target namespace) defined by the targetNamespace attribute of the <definitions> element.
Types	Defined by one occurrence of the <types> element. This section provides data type definitions used to describe the messages exchanged between a Web service and the Web service client. These data type definitions typically use the XML Schema specification.
Messages	Defined by one or more <message> elements. Each <message> element consists of multiple logical parts, consisting of the message name and the message parts. The message name is a unique name that identifies the message. The message parts specify the part names and data types.
Port types	Defined by one or more <portType> elements. Each <portType> element defines a set of abstract operations (one <operation> element for each operation) and the abstract messages (operation parameters) involved. Each port type is uniquely named among all port types defined within the WSDL file.
Bindings	Defined by one or more <binding> elements. This section specifies how the client and Web service exchange messages for each operation (<operation> element). Each binding element contains information that specifies the protocol by which the client accesses the Web service. OpenEdge supports the SOAP protocol, which specifies a message protocol that includes an envelope, header, and body. For SOAP, the binding information includes a transport attribute that identifies the transport protocol used by the binding. OpenEdge supports the transport protocols, HTTP, HTTPS (HTTP/S), and FILE. A SOAP binding also identifies a format used for each operation to exchange messages, indicated by the style and use attributes. OpenEdge supports the message formats named style/use respectively as: RPC/Encoded RPC/Literal Document/Literal Each <binding> element corresponds to a previously-defined <portType> element, specifying appropriate information about the same set of operations. As described for port types, a <portType> element defines the abstract elements of each operation, the parameters and their data types that the client must interact with at the logical level. The corresponding <binding> element defines the physical details of how messages for these same operations are exchanged over the network. Note: The message style also has an effect on how the Messages and Types sections relate to each other to define messages for operation parameters.
Services	Defined by zero or more occurrences of the <service> element. This is an optional section that defines a collection of related endpoints (ports). Each <service> element is uniquely identified within this section of the WSDL file by a name and can contain several <port> elements. Each <port> element specifies a binding and a location at which that binding's operations can be accessed by the Web service client. Note: A Web service is identified by a combination of a single binding and endpoint. If no <service> elements exist in the WSDL file, the Web service client must obtain a valid endpoint, typically in the form of a URL, where the operations for each binding can be accessed on the Internet.

For more information on how to use the WSDL file to help program the 4GL interface to a Web service, see Chapter 8, " Analyzing WSDL for Progress 4GL Access to Web Services." For complete information on WSDL and its meaning, see the official WSDL specification at the following URL:

http://www.w3.org/TR/wsdl

OpenEdge WSDL Analyzer

OpenEdge makes accessing Web services from the 4GL much easier by providing a utility (the WSDL Analyzer) that can read the WSDL file and produce a reference guide that documents exactly how to use the 4GL to access the Web service. This guide is a series of HTML documents with hyperlinks that clearly define all Web service operations and their 4GL interfaces, including how complex Web service data types are represented in the WSDL. It also provides the binding information necessary to access the Web service on the Internet. Finally, it includes any internal WSDL file comments as documentation from the Web service provider.

To make use of the OpenEdge features that allow you to access a Web service at run time, the client application must have access to a current WSDL file for the Web service you want to use. Using the reference output is optional, but highly recommended to most effectively structure your code to access the Web service. The way OpenEdge interprets the run-time invocation of Web service operations is consistent with the WSDL Analyzer processing to produce its reference documentation. For an example of how the WSDL Analyzer can help you to program your 4GL interaction with a Web service, see the "Interacting with a Web service and its operations" section. For more information on WSDL, how the 4GL maps Web services based on WSDL, and how you can use the WSDL Analyzer to help you write the necessary 4GL, see Chapter 8, " Analyzing WSDL for Progress 4GL Access to Web Services."